Skip to content

uri: Unify example URL for RFC 3986 getters#5471

Open
TimWolla wants to merge 1 commit intophp:masterfrom
TimWolla:uri-rfc3986-getter-example
Open

uri: Unify example URL for RFC 3986 getters#5471
TimWolla wants to merge 1 commit intophp:masterfrom
TimWolla:uri-rfc3986-getter-example

Conversation

@TimWolla
Copy link
Copy Markdown
Member

@TimWolla TimWolla commented Apr 6, 2026

This new example URL includes all possible components and each of the component includes a meaningful difference between the “normalized” and “raw” version to make it easy for a reader to see what each of the getters refers to and what kind of normalization to expect.

This new example URL includes all possible components and each of the component
includes a meaningful difference between the “normalized” and “raw” version to
make it easy for a reader to see what each of the getters refers to and what
kind of normalization to expect.
@TimWolla TimWolla requested a review from kocsismate April 6, 2026 18:37
@kocsismate
Copy link
Copy Markdown
Member

kocsismate commented Apr 7, 2026

My original idea was to use a basic example just to illustrate the basic behavior of each method, and then to add another example to illustrate the specification specific behavior (wrt. normalization or IDNA).

I'm not sure that people less familiar with URI topic will have an easy time to understand what's going on if they are presented such a long and complex URI. IMO the example would be more clear if the URI was shorter. An example:

$uri = new \Uri\Rfc3986\Uri('https://example.com#%62ook.uri');

var_dump($uri->getFragment());
$uri = new \Uri\Rfc3986\Uri('HTTPS://p%68p:elephp%61nt@WWW.PHP.NET:443/manual/ch%61nge.php?p%61ge=en/book.uri.php#%62ook.uri');

var_dump($uri->getFragment());

It's (more) difficult to find the fragment in the latter example, even for me, since there are a lot of unrelated symbols to skip.

@TimWolla
Copy link
Copy Markdown
Member Author

I'm not sure that people less familiar with URI topic will have an easy time to understand what's going on

I think those folks in particular can benefit when all the examples use the same URL, since they can then compare the different getters to see which of the getters relates to which part of the URL. Having different URLs where some of the parts are left out can result in ambiguity. For example using http://example.com/foo/bar hides that the path will end when encountering ? and #. This might mislead users to believe that the path is everything after the third slash.

Basically when I look at the documentation page for a specific getter, then I'm interested in the specifics of that getter.

I think simpler URLs are better suited for the documentation of the constructor or ::parse() where users care more about “how do I get this to work” rather than extracting specific stuff.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants